<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta name="robot" content="index,follow">
<title>Module rdg - Distributed pseudo random number generators - Forth Foundation Library</title>
</head>
<body>
<h2>rdg - Distributed pseudo random number generators</h2>
<h3>Module Description</h3>
<p>The rdg module implements pseudo random number generators with a
distribution. The module requires a pseudo random generator with an
uniform distribution which returns floating point random numbers with
a range of [0,1>. Due to the extensive use of the floating point stack,
this module has an environmental dependency.
</p>
<h3>Module Words</h3>
<dl>
</dl>
<h4>Distributed Random generator structure</h4>
<dl>
<dt><a name="word1"><b>rdg%</b>	( -- n )</dt>
<dd>Get the required space for a rdg variable</dd>
</dl>
<h4>Distributed random generator creation, initialisation and destruction</h4>
<dl>
<dt><a name="word2"><b>rdg-init</b>	( x xt rdg -- )</dt>
<dd>Initialise the generator with the random generator xt and its data x</dd>
<dt><a name="word3"><b>rdg-create</b>	( x xt "&lt;spaces&gt;name" -- ; -- rdg )</dt>
<dd>Create a named random generator in the dictionary with the random generator xt and its data x</dd>
<dt><a name="word4"><b>rdg-new</b>	( x xt -- rdg )</dt>
<dd>Create a new random generator on the heap with the random generator xt and its data x</dd>
<dt><a name="word5"><b>rdg-free</b>	( rdg -- )</dt>
<dd>Free the random generator from the heap</dd>
</dl>
<h4>Random generator words</h4>
<dl>
<dt><a name="word6"><b>rdg-uniform</b>	( F: r1 r2 -- r3 ; rdg -- )</dt>
<dd>Generate a random number with a uniform distribution in the range of [r1,r2&gt;</dd>
<dt><a name="word7"><b>rdg-normal</b>	( F: r1 r2 -- r3 ; rdg -- )</dt>
<dd>Generate a random number with a normal or Gaussian distribution with mu or mean r1 and sigma or standard deviation r2</dd>
<dt><a name="word8"><b>rdg-exponential</b>	( F: r1 -- r2 ; rdg -- )</dt>
<dd>Generate a random number with an exponential distribution with mu or mean r1 [&gt;0]</dd>
<dt><a name="word9"><b>rdg-gamma</b>	( F: r1 r2 -- r3 ; rdg -- )</dt>
<dd>Generate a random number with a gamma distribution with alpha r1 [&gt;0] and beta r2 [&gt;0], alpha*beta = mean, alpha*beta^2 = variance</dd>
<dt><a name="word10"><b>rdg-beta</b>	( F: r1 r2 -- r3 ; rdg -- )</dt>
<dd>Generate a random number with a beta distribution with alpha r1 [&gt;0] and beta r2 [&gt;0], alpha*beta = mean, alpha*beta^2 = variance</dd>
<dt><a name="word11"><b>rdg-binomial</b>	( F: r -- ; u1 rdg -- u2 )</dt>
<dd>Generate a random number with a binomial distribution with probability r [0,1] and trails u1 [&gt;=0]</dd>
<dt><a name="word12"><b>rdg-poisson</b>	( F: r -- ; rdg -- u )</dt>
<dd>Generate a random number with a Poisson distribution with mean r [&gt;=0]</dd>
<dt><a name="word13"><b>rdg-pareto</b>	( F: r1 r2 -- r3 ; rdg -- )</dt>
<dd>Generate a random number with a Pareto distribution with alpha r1 [&gt;0] the scale parameter and r2 [&gt;0] the shape parameter</dd>
<dt><a name="word14"><b>rdg-weibull</b>	( F: r1 r2 -- r3 ; rdg -- )</dt>
<dd>Generate a random number with a Weibull distribution with alpha r1 [&gt;0] the scale parameter and beta r2 [&gt;0] the shape parameter</dd>
</dl>
<h3>Examples</h3>
<pre>
include ffl/rng.fs
include ffl/rdg.fs


\ Create a random generator variable in the dictionary with seed 5489

5489 rng-create rng1

\ Create a distributed random generator in the dictionary with the rng1 random generator
\ The distributed random generator expects the state and the word that generates random
\ numbers in the range [0..1&gt;.

rng1 ' rng-next-float rdg-create rdg1

\ Generate a normal or gaussian random number with mean 1.0 and stddev 0.5

1E+0 0.5E+0 rdg1 rdg-normal f. cr

\ Generate an exponential random number with mean 2.0

2E+0 rdg1 rdg-exponential f. cr

\ Generate a gamma random number with alpha 2.0 and beta 0.5

2E+0 0.5E+0 rdg1 rdg-gamma f. cr

\ Generate a beta random number with alpha 2.0 and beta 0.5

2E+0 0.5E+0 rdg1 rdg-beta f. cr

\ Generate a binomial random number with probability 0.4 and trails 15

0.4E+0 15 rdg1 rdg-binomial u. cr

\ Generate a poisson random number with mean 17.0

17E+0 rdg1 rdg-poisson u. cr

\ Generate a pareto random number with alpha 3.5 and beta 2.0

3.5E+0 2E+0 rdg1 rdg-pareto f. cr

\ Generate a weibull random number with alpha 3.5 and beta 2.0

3.5E+0 2E+0 rdg1 rdg-weibull f. cr



\ Create a distributed random generator variable on the heap

rng1 ' rng-next-float rdg-new value rdg2

\ Generate an uniform random number in the range of [34.5,34.6&gt;

34.5E+0 34.6E+0 rdg2 rdg-uniform f. cr

\ Free the variable from the heap

rdg2 rdg-free

</pre>
<hr>
<div align="center">generated 24-Jul-2010 by <b>ofcfrth-0.10.0</b></div>
</body>
</html>
